RuleManagerService - Installation & Configuration

Please note that this document is still under revision, so slight changes still might occur before the final version of this draft.

Version 6.3

Introduction

COMPASS 6.3 allows a client application to communicate with the COMPASS engine via REST Services. The COMPASS engine consists of the REST components CompassService and RuleManagerService.

From on COMPASS 6.3, the REST services have been split up into CompassService and RuleManagerService: CompassService is Compass' public API (described in detail here), RuleManagerService is the internal API used by RuleManagerApp and not meant for public usage.

Both CompassService and RuleManagerService are Web applications that need to be deployed in a Servlet Container or can run as a Spring Boot application. They work in a stateless manner, and as such it allows easy deployment and scalability including cloud architectures.

This document describes the installation and configuration of the RuleManagerService which is the backend for the RuleManagerApp and provides the necessary REST-services. Please note that this API should not be used by anyone but RuleManagerApp only. The publicly available REST methods provided by COMPASS are documented at REST-API

Prerequisites

RuleManagerService can be deployed in any Java servlet container that supports at least Servlet API 5.0. We recommend the lightweight Java web server Apache Tomcat.

From on version 6.3, RuleManagerService requires Java 17.

Functionality of the RuleManager Service

REST-Services provided by RuleManagerService and used by RuleManagerApp are for internal use only and therefore are not described here.

Installation

The RuleManagerService distribution consists of the archive RuleManagerService.war. It can be deployed in a Servlet Container (see Deployment in a Servlet Container) or as a standalone application using Spring Boot (see Standalone Server (Spring Boot)).

Deployment in a Servlet Container

RuleManagerService.war containing the RuleManagerService should be deployed in your Servlet Container (i.e. Tomcat: webapps directory, OpenLiberty: dropins directory). If required, restart the container.

Standalone Server (Spring Boot)

The RuleManagerService.war contains a runnable environment that can be started with the spring WarLauncher. For quick testing, it is possible to start the WebApp without a third-party Servlet Container:

Copy RuleManagerService.war file to your Compass lib directory.

Make sure Java 17 is installed, and run the following command using Java 17:

java -cp lib\RuleManagerService.war;databaseDriver org.springframework.boot.loader.launch.WarLauncher  --spring.configname=RuleManagerService

The delivery includes a batch file bin\startRuleManagerService.bat that starts RuleManagerService as a Spring Boot application.

Configuration

RuleManagerService needs configuration files which define the environment and the data to work with. This configuration-file may use one of the following formats:

Format	File-Name
Properties	RuleManagerService.properties
YAML	RuleManagerService.yml
JSON	RuleManagerService.json

Format

File-Name

Properties

RuleManagerService.properties

YAML

RuleManagerService.yml

JSON

RuleManagerService.json

Following, we will explain the configuration as properties. The difference between the formats mentioned above are explained in RuleManagerService.properties - application.properties

The main property file is called either RuleManagerService.properties (default file name) or RuleManagerService.yml; in Open Liberty, the file needs to be named application.properties. The contents of the files are described in detail in RuleManagerService.properties - application.properties. We strongly recommend using COMPASS’ ability to use DataSources instead of pure JDBC calls. Therefore, please create the appropriate DataSources (see Data Source properties).

Spring Boot

When the RuleManagerService is started as a Spring Boot application with the batch file bin\startRuleManagerService.bat, the path to the configuration-file is:

config\RuleManagerService.properties

The file name is defined by the --spring.config.name parameter in said file (see Standalone Server (Spring Boot)) and should be located in the [COMPASS-installation]/Config directory.

Apache Tomcat / Standard Servlet Container

The following instructions describe the standard procedure of a deployment within a Standard Servlet Container. As an example, deployment within Apache Tomcat is explained:

Please be aware that when running RuleManagerService from on version 6.3 on Apache Tomcat, you will need Apache Tomcat 10.0.0 or higher.

When the RuleManagerService is being deployed within a Standard Servlet Container, it is up to the administrator to place to file RuleManagerService.properties to any location and adapt the environment-entry in RuleManagerService/META-INF/context.xml accordingly, i.e.

$CATALINA_HOME/COMPASSConfig/RuleManagerService.properties

The location of the above mentioned file is defined in RuleManagerService/META-INF/context.xml, and can be adapted:

<?xml version="1.0" encoding="UTF-8"?>
    <Context path="/">
        <Environment    name="spring.config.location"
                        value="file:../COMPASSConfig/RuleManagerService.properties"
                        type="java.lang.String"/>

The file RuleManagerervice.properties is part of the installation package and will be delivered outside the WAR archive.

Open Liberty / WebSphere

The following instructions describe the procedure of a deployment within an IBM’s Open Liberty. It is also a template for deployment within IBM’s WebSphere. As an example, deployment within Open Liberty is explained:

When RuleManagerService is being deployed in Open Liberty, the file application.properties needs to be placed in $/{server.config.dir} i.e. /opt/wlp/usr/servers/defaultServer.

The default context name of RuleManagerService is "RuleManagerService". If this needs to be changed, the WAR archive of RuleManagerService needs to be unpacked and the file WEB-INF/classes/ibm-web-ext.xml needs to be adapted. The context name can be changed by editing the entry context-root:

 <web-ext xmlns="http://websphere.ibm.com/xml/ns/javaee"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="http://websphere.ibm.com/xml/ns/javaee
   http://websphere.ibm.com/xml/ns/javaee/ibm-web-ext_1_0.xsd"
   version="1.0">

   <reload-interval value="0"/>
   <context-root uri="/RuleManagerService"/>
   <enable-file-serving value="true"/>
   <enable-reloading value="true"/>
</web-ext>

After editing, the WAR archive needs to be re-packed and can be deployed.

Wildfly / JBoss

If you haven’t done so, deploy your database driver to JBoss / Wildfly and create the DataSources needed for COMPASS (see example below). You can also configure RuleManagerService in such a way that it uses pure JDBC connections (see Installation: Database), however, we strongly recommend to use DataSources when deploying RuleManagerService on JBoss / WildFly.

Since there are multiple options specifying DataSources in JBoss / WildFly, our example below shows one possible way to define the DataSources. We therefore adapt %JBOSS_HOME%/standalone/configuration/standalone.xml. If you want to configure the DataSources in a different way, please consult the documentation of your application server or talk to your database administrator.

        <subsystem xmlns="urn:jboss:domain:datasources:6.0">
            <datasources>
                <datasource jndi-name="java:jboss/COMPASSKnowledge" pool-name="COMPASSKnowledge">
                    <connection-url>jdbc:mariadb://localhost:3306/dbname</connection-url>
                    <driver-class>org.mariadb.jdbc.Driver</driver-class>
                    <driver>mariadb-java-client-2.7.1.jar</driver>
                    <security>
                        <user-name>user</user-name>
                        <password>password</password>
                    </security>
                    <validation>
                        <valid-connection-checker class-name="org.jboss.jca.adapters.jdbc.extensions.mysql.MySQLValidConnectionChecker"/>
                        <validate-on-match>true</validate-on-match>
                        <background-validation>false</background-validation>
                        <exception-sorter class-name="org.jboss.jca.adapters.jdbc.extensions.mysql.MySQLExceptionSorter"/>
                    </validation>
                </datasource>
                <datasource jndi-name="java:jboss/COMPASSCache" pool-name="COMPASSCache">
                    <connection-url>jdbc:mariadb://localhost:3306/dbname</connection-url>
                    <driver-class>org.mariadb.jdbc.Driver</driver-class>
                    <driver>mariadb-java-client-2.7.1.jar</driver>
                    <security>
                        <user-name>user</user-name>
                        <password>password</password>
                    </security>
                </datasource>
                <datasource jndi-name="java:jboss/COMPASSCase" pool-name="COMPASSCase">
                    <connection-url>jdbc:mariadb://localhost:3306/dbname</connection-url>
                    <driver-class>org.mariadb.jdbc.Driver</driver-class>
                    <driver>mariadb-java-client-2.7.1.jar</driver>
                    <security>
                        <user-name>user</user-name>
                        <password>password</password>
                    </security>
                </datasource>
            </datasources>
        </subsystem>

When RuleManagerService is being deployed within a Standard Servlet Container, it is up to the administrator to place to file RuleManagerService.properties to any location and adapt the environment-entry in the deployment descriptor WEB-INF/web.xml accordingly (reminder: you’ll have to re-package the war archive and re-deploy).

Let’s say the configuration file is in $JBOSS_HOME, the entry would look like

<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns="http://java.sun.com/xml/ns/javaee"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://java.sun.com/xml/ns/javaee
		  http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd"
         version="3.0">
    <env-entry>
        <env-entry-name>spring.config.location</env-entry-name>
        <env-entry-type>java.lang.String</env-entry-type>
        <env-entry-value>file:../COMPASSConfig/RuleManagerService.properties</env-entry-value>
    </env-entry>
</web-app>

In JBoss / WildFly, if running them with default logging configuration, the archive SL4J needs to be excluded from COMPASS' classpath. This has already been configured inside the web app at META-INF/jboss-deployment-structure.xml - so if this needs to be changed again, please adapt said file and re-package the war archive.

<jboss-deployment-structure>
    <deployment>
    <!-- Exclusions allow you to prevent the server from automatically adding some dependencies     -->
        <exclusions>
            <module name="org.slf4j" />
            <module name="org.slf4j.impl" />
        </exclusions>
    </deployment>
</jboss-deployment-structure>

Profiles

RuleManagerService works with profiles regarding Authorization / Authentication. Depending on the chosen profile, RuleManagerService will either use Spring Authorization (OAuth2) or Keycloak. It is also possible to run RuleManagerService without any Authorization / Authentication.

The desired Authorization / Authentication option is to specified in the property spring.profiles.active in the file RuleManagerService.properties or RuleManagerService.yml (see Configuration).

There are 5 profiles available to customize the type of Authorization / Authentication:

Table 1. Authorization Profiles
Profile	Explanation
`default`	Mandatory
`keycloakAuthorization`	Activate the Keycloak Authorization Configuration
`springAuthorization`	Activate Spring Authorization Configuration
`noAuthorization`	Service Endpoints are not secured. RuleManagerApp does not ask for a user/password
`dbAuthorization`	Service Endpoints are not secured. RuleManagerApp will ask for user/password, which will be confirmed by RuleManagerService

2 profiles need to be specified - default plus the corresponding Authorization profile. The profile default always needs to be specified plus either one of the profiles keycloakAuthorization, springAuthorization or noAuthorization .

If not exactly 2 profiles are specified or if the profile default is missing, the application will not start.

Table 2. Valid Authorization Profiles
Profiles	Explanation
`spring.profiles.active=default,springAuthorization`	RuleManagerService secured by Spring Authorization
`spring.profiles.active=default,keycloakAuthorization`	RuleManagerService secured by Keycloak Authorization
`spring.profiles.active=default,noAuthorization`	Endpoints are not secured
`spring.profiles.active=default,dbAuthorization`	Endpoints are not secured

RuleManagerService.properties - application.properties

Usually, configuration properties are specified in the file RuleManagerService.properties. In Open Liberty (WebSphere), the file application.properties is used instead.

The content of both these files is identical and can be grouped into 4 sections: System properties, Spring Boot related properties, authorization properties and logging properties.

It is also possible to pass the configuration-properties as command-line-parameters to RuleManagerService.

System properties

RuleManagerService stores some information in the property-files mentioned below. Those properties are defined in the file [compass.server.home]/config/server/compass.properties.

In addition, RuleManagerService needs to know the system-name to work with and additional properties when being started.

After modification of any of above-mentioned parameters, the web server should be restarted for the changes to take effect.

The following 3 properties are used to configure these:

Property Name	Description
rulemanager.server.home	Location where the 3 above mentioned files/directory are located. For Spring Boot, start with the default batch file set to rulemanager.server.home=. It is also possible to define an absolute path. Example for Apache Tomcat: rulemanager.server.home=${CATALINA_HOME}/COMPASSConfig Example for Open Liberty / WebSphere: rulemanager.server.home=${server.config.dir}/COMPASSConfig_
rulemanager.systemname	Name of the system to be used, and which is defined in compass.properties
rulemanager.fullloadsystem	true or false: A simple preload is always done at start-up. Should this property be set to true, the whole Knowledge Data gets loaded into memory at application start-up, which results in a longer start-up time.

Property Name

Description

rulemanager.server.home

Location where the 3 above mentioned files/directory are located.
For Spring Boot, start with the default batch file set to rulemanager.server.home=. It is also possible to define an absolute path.

Example for Apache Tomcat:
rulemanager.server.home=${CATALINA_HOME}/COMPASSConfig

Example for Open Liberty / WebSphere:
rulemanager.server.home=${server.config.dir}/COMPASSConfig_

rulemanager.systemname

Name of the system to be used, and which is defined in compass.properties

rulemanager.fullloadsystem

true or false:
A simple preload is always done at start-up. Should this property be set to true, the whole Knowledge Data gets loaded into memory at application start-up, which results in a longer start-up time.

Viewname properties

Property Name

Description

rulemanager.database.knowledge.url

Url of the knowledge database

rulemanager.database.knowledge.user

Username of the knowledge database

rulemanager.database.knowledge.password

Password of the knowledge database

rulemanager.database.knowledge.driver

Driver class of the knowledge database

rulemanager.database.knowledge.reconnect

Boolean. If this property is included with the value “true”, then the connection described by the parame-ters above will be reconnected, if it has been dropped or is otherwise unavailable. This feature can be used e.g. when the database server drops unused connections after a certain time (e.g. 30 minutes). Set this property only if required, as it slows down the database performance. When this property is not in included in the compass.properties-file, or its value is set to anything other than “true”, the reconnect is not attempted.

rulemanager.database.knowledge.real

java.lang.Float or java.lang.Double; responsible for the representation of decimal numbers

rulemanager.database.knowledge.viewname.Author

The Author table is known under this name

rulemanager.database.knowledge.viewname.BoolOrInt

The BoolOrInt table is known under this name

rulemanager.database.knowledge.viewname.Double

The Double table is known under this name

rulemanager.database.knowledge.viewname.Group

The GroupID table is known under this name

rulemanager.database.knowledge.viewname.Index

The Index table is known under this name

rulemanager.database.knowledge.viewname.Keys

The Keys table is known under this name

rulemanager.database.knowledge.viewname.Name

The Name table is known under this name

rulemanager.database.knowledge.viewname.PersObj

The PersObj table is known under this name

rulemanager.database.knowledge.viewname.Relation

The Relation table is known under this name

rulemanager.database.knowledge.viewname.Search

The Search table is known under this name

rulemanager.database.knowledge.viewname.String

The String table is known under this name

Spring Boot properties

The following properties are used to configure RuleManagerService when started outside a Servlet Container but being run as a Spring Boot application.

When running in a Servlet Container, these values are typically defined within the Servlet Container and can be omitted (commented out).

Property Name	Description
server.port	REST service is listening on this port, only relevant if the service is running stand-alone
server.servlet.contextPath	REST API prefix, only relevant if service is running stand-alone
server.sessionTimeout	timeout, only relevant if the service is running stand-alone
spring.jmx.enabled	Don’t expose management beans to the JMX domain

Property Name

Description

server.port

REST service is listening on this port, only relevant if the service is running stand-alone

server.servlet.contextPath

REST API prefix, only relevant if service is running stand-alone

server.sessionTimeout

timeout, only relevant if the service is running stand-alone

spring.jmx.enabled

Don’t expose management beans to the JMX domain

Data Source properties

The next property allows the definition of a Java Datasource for the database connection to access the: Knowledge Ddta. Set value to "none", if you don’t want to use a DataSource but want to use the database configuration in ${compass.server.home}/config/server/compass.properties Set values to a JNDI Value, if you want to use Datasource of the servlet container. For Apache Tomcat, define <ResourceLink> in context.xml and <Resource> in server.xml needs to be defined..

Property Name	Description
knowledge.datasource.jndi	Datasource for knowledge data

Property Name

Description

knowledge.datasource.jndi

Datasource for knowledge data

Should the entry xxxxxx.datasource.jndi be set to none or to a value that has not really been defined in the servlet container, a JDBC database connection will be created using the system-properties from the file $\{compass.server.home}/config/server/compass.properties.

When defining the Datasource for the Knowledge Data, the corresponding connection-properties in the compass.properties-file can be omitted:

Knowledge Data:

[System-name].database.url
[System-name].database.driver
[System-name].database.user
[System-name].database.password

Authorization properties

This part is only required when the RuleManagerService is used together with the COMPASS Authorization Server (OAuth2), meaning the profiles default and `springAuthorization`are activated (see Profiles). The installation of COMPASS Authorization Server providing OAuth2-authorization is described in the document Authorization Server. The corresponding properties are described in the document REST-API-Security

Property Name Description

Property Name	Description
rulemanager.security.cors,enabled	define if CORS is enabled
rulemanager.security.cors.crossOrigin.urls	specify URLs for which CORS is allowed. URLs have to be entered incl. protocol (i.e. http / https) and port. Multiple URLs cam be entered as a list separated by comma
rulemanager.security.clientId	define the client id for the oauth server default: rulemanager-client
spring.security.oauth2.resourceserver.jwt.issuer-uri	Used by Authorization Server. Please do not change the default value. default: ${compass.security.authServerUrl}
springdoc.api-docs.version	openapi_3_1 (constant - don’t change)
rulemanager.security.authServerUrl	define the new Authorization server URL / Keycloak Authorization server URL Example: Keycloak: rulemanager.security.authServerUrl=https://localhost:8085/realms/Compass Authorization server: rulemanager.security.authServerUrl=https://localhost:8091/AuthorizationServer
rulemanager.security.requireHttps	If set to true, Authorization server URL needs to be https
rulemanager.security.sessionCheckInterval	tokens will be checked in the defined regular interval if it is valid (ms)
rulemanager.security.roleBasedResourceAccessEnabled	It is used to secure the REST API call. If enabled, only users with the role `RULES` can access the REST API. If disabled, then any user regardless of their role, can access the REST API. User roles can be configured in Authorization Server It is disabled by default
rulemanager.security.springAuthorization.tokenBlacklistingOnLogoutEnabled	During login with SpringAuthorization server, the frontend uses JWT token so that users remain authorized for a certain period of time without having to log in again. This token has remained valid until expiration time even after explicit logout. When tokenBlacklistingOnLogoutEnabled property is set to true, then it will blacklist the token after logout so that the REST API cannot be accessed with this token. This Token blacklisting supports only springAuthorization profile (see Profiles). It is set to true by default

rulemanager.security.cors,enabled

define if CORS is enabled

rulemanager.security.cors.crossOrigin.urls

specify URLs for which CORS is allowed. URLs have to be entered incl. protocol (i.e. http / https) and port. Multiple URLs cam be entered as a list separated by comma

rulemanager.security.clientId

define the client id for the oauth server
default: rulemanager-client

spring.security.oauth2.resourceserver.jwt.issuer-uri

Used by Authorization Server. Please do not change the default value. default: ${compass.security.authServerUrl}

springdoc.api-docs.version

openapi_3_1 (constant - don’t change)

rulemanager.security.authServerUrl

define the new Authorization server URL / Keycloak Authorization server URL
Example:

Keycloak: rulemanager.security.authServerUrl=https://localhost:8085/realms/Compass

Authorization server: rulemanager.security.authServerUrl=https://localhost:8091/AuthorizationServer

rulemanager.security.requireHttps

If set to true, Authorization server URL needs to be https

rulemanager.security.sessionCheckInterval

tokens will be checked in the defined regular interval if it is valid (ms)

rulemanager.security.roleBasedResourceAccessEnabled

It is used to secure the REST API call. If enabled, only users with the role RULES can access the REST API. If disabled, then any user regardless of their role, can access the REST API. User roles can be configured in Authorization Server It is disabled by default

rulemanager.security.springAuthorization.tokenBlacklistingOnLogoutEnabled

During login with SpringAuthorization server, the frontend uses JWT token so that users remain authorized for a certain period of time without having to log in again. This token has remained valid until expiration time even after explicit logout. When tokenBlacklistingOnLogoutEnabled property is set to true, then it will blacklist the token after logout so that the REST API cannot be accessed with this token. This Token blacklisting supports only springAuthorization profile (see Profiles). It is set to true by default

Integration with Keycloak

In order to run RuleManagerService, the following profiles have to be activated in the file RuleManagerService.properties or RuleManagerService.yaml (see RuleManagerService.poperties / application.properties. A Customer Keycloak Realm Issuer URL needs to be configured.

Role based authentication configuration in Keycloak

If users should only access the REST API based on their role, please follow these steps to configure it in Keycloak:

Login to Keycloak admin console in a browser
Select the corresponding realm.
Go to Client scopes and click the roles client scope link.
Go to the Mappers tab and click the client roles link.
Change Token Claim Name to authorities so that the user roles will be saved with this attribute name in the token.

Note: RuleManagerService will read the user roles from the authorities attribute in the token.

The Issuer Url can be found if you open Keycloak Admin Console, select the corresponding Realm and click Realm Settings. On the right side, you will find the OpenID Endpoint Configuration link. Click the link, it will open a new tab and on the beginning, you will find the Issuer Url.

Example 1. Example from Keycloak

"issuer":"http://localhost:8080/realms/RuleManagerApp"

Example 2. Example configuration in RuleManagerService

spring.profiles.active=default,keycloakAuthorization
spring.security.oauth2.resourceserver.jwt.issuer-uri=http://localhost:8080/realms/RuleManagerApp

Logging

RuleManager Service

In RuleManagerService logging can be configured via properties in the file RuleManagerService.[properties | yaml | json]. For a full overview about properties and logging features in RuleManagerService (see Properties Overview of RuleManagerService).

Verifying the installation

After updating the configuration-file, the installation needs to be verified.

For both installation types (Spring Boot app - standalone - or deployment in a Servlet Container, please perform the following steps:

Deployment as Spring Boot app (stand-alone)

Start RuleManagerService as Spring Boot app (stand-alone):

[COMPASS-installation-directory]/bin/startRESTService.bat

Verify in your console, that RuleManagerService started:

In the CMD-window or the log-file specified, you should see a message like

2023-03-14 13:05:47,299 [INFO ] c.c.c.r.RuleManagerServiceApp:61 - Started RuleManagerServiceApp in 65.43 seconds (JVM running for 308.249)

Deployment in Servlet Container

Perform the following steps:

Start the Servlet Container if not already started and deploy the application
Check that the RuleManagerService was deployed correctly (using administration tools of your Web Server).
Alternatively, you can check the logfile you’ve specified: It should contain an entry like

2023-03-14 13:05:47,299 [INFO ] c.c.c.r.RuleManagerServiceApp:61 - Started RuleManagerServiceApp in 65.43 seconds (JVM running for 308.249)

Test connectivity (for both deployment methods)

RuleManagerService has integrated SWAGGER support to describe and document its RESTful API. To view this API documentation open the following URL in your browser:

http(s)://[host]:port/RuleManagerService/api.html

Example:

http://localhost:8080/RuleManagerService/api.html

If RuleManagerService has been installed successfully, your browser should display the SWAGGER representation of RuleManagerService RESTful API: